home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / vtkermit.arc / MENU.DOC < prev    next >
INI File  |  1986-02-13  |  7KB  |  163 lines
  1. [MENU.DOC] -- Documentation for VTKermit's Menu Facility -- 1 Feb 1986
  2.  
  3. VTKermit's Menu Facility is a mechanism which permits you to present a user
  4. with a simplified menu interface instead of the normal VTKermit> prompt.  The
  5. issue here is not simply commands versus menus, since the two modes are not
  6. equivalent.  Basically, menus allow a VTKermit customizer to build a "turnkey"
  7. system to be used by less-sophistated users.
  8.  
  9. The VTKermit software has three major modes, each of which has submodes.  The
  10. major modes are:
  11.  
  12.   1)  Terminal mode, in which VTKermit emulates a DEC VT100 terminal;
  13.   2)  File transfer mode, in which VTKermit sends or receives files in either
  14.     of the Kermit or XMODEM protocols; and
  15.   3)  Command mode, which is used to set parameters and control the program.
  16.  
  17. Menu mode is a submode of command mode.  A MENU command issued while at the
  18. VTKermit> prompt (or from within a command file, or from the command line)
  19. will immediately search for the selected menu file (VTKERMIT.MNU by default)
  20. and display it, as described in later paragraphs.  Alternatively, a SET MODE
  21. MENU command will cause the program to display the menu at any time that it
  22. would ordinarily present its "VTKermit> " prompt and wait for keyboard input.
  23.  
  24. You may specify the name of the menu file with a SET MENU-FILE command.  If
  25. you don't do this, the name of the menu file will be VTKERMIT.MNU.
  26.  
  27. A menu (as displayed onscreen) is a box containing a title line and a number
  28. of items to choose between.  When the menu is first displayed, a highlight bar
  29. will appear over the first of the items.  You can move the highlight bar up
  30. and down in predictable ways:  up-arrow and down-arrow move the bar up and
  31. down (as do left- and right-arrow), while Home and PgUp move to the top item
  32. and End and PgDn move to the last item.  Once you have moved the highlight bar
  33. to the item you want, press Enter (CR) to select it.
  34.  
  35. Alternatively, you can type a letter (or number or other single ASCII
  36. character) to immediately select the next item which begins with that letter.
  37. If you type a character that does not begin any menu item, the program will
  38. beep at you.
  39.  
  40. Finally, if none of the displayed items is what you want, you can type
  41. CONTROL-C to break yourself out of the menu and return to the command prompt.
  42. This protects you in case you build a menu that won't do what you want.  (You
  43. can always get out.)
  44.  
  45. Menu files are normal ASCII text files with lines ending in CR-LF.  There are
  46. three types of lines in a menu file.
  47.  
  48.   1)  The file should begin with a line starting with a percent-sign.  This
  49.     line will be used as the title of the menu, and the text on the line
  50.     will be displayed at the top of the menu.
  51.  
  52.   2)  The line following the title should begin with an asterisk.  This line
  53.     is an item label, and will be displayed as the first item in the menu.
  54.     You may want to force each item label to begin (after the asterisk)
  55.     with a unique character, because items are selectable by typing their
  56.     first character (as in Lotus 1-2-3 and many other programs).
  57.  
  58.   3)  The third line in the file should begin with a plus-sign.  This line
  59.     contains text to be executed as a normal VTKermit command.  Following
  60.     the third line of the file, additional lines may be either command
  61.     lines or item labels.  Item labels should be separated by command
  62.     lines, and there may be only one title line, the first line in the
  63.     file.
  64.  
  65. A simple example will help to clarify this.  The following menu allows the
  66. user only three options:  Push (to new COMMAND.COM), Exit (to DOS) or Connect
  67. (to terminal mode).
  68.  
  69.     %This is a very simple example of a menu file
  70.     *Push (to new COMMAND.COM)
  71.     +Push
  72.     *Exit (to DOS)
  73.     +Exit
  74.     *Connect (to terminal mode)
  75.     +Connect
  76.  
  77. Much more complex menu structures may be constructed.  In fact, by using the
  78. SET MODE MENU and SET MENU-FILE commands, a tree structured menu arrangement
  79. may be built in which selecting a menu item causes a second menu to be
  80. displayed.  The following trio of menu files works this way.
  81.  
  82.     [VTKERMIT.MNU]
  83.     %Main Menu
  84.     *1 -- Select submenu 1
  85.     +Set Mode Menu
  86.     +Set Menu-File Menu1.Mnu
  87.     *2 -- Select submenu 2
  88.     +Set Mode Menu
  89.     +Set Menu-File Menu2.Mnu
  90.  
  91.     [MENU1.MNU]
  92.     %Submenu 1
  93.     *A -- Option A
  94.     +Set Menu-File VTKermit.Mnu
  95.     +Echo Option A selected from submenu 1
  96.     *B -- Option B
  97.     +Set Menu-File VTKermit.Mnu
  98.     +Echo Option B selected from submenu 1
  99.  
  100.     [MENU2.MNU]
  101.     %Submenu 2
  102.     *A -- Option A
  103.     +Set Menu-File VTKermit.Mnu
  104.     +Echo Option A selected from submenu 2
  105.     *B -- Option B
  106.     +Set Menu-File VTKermit.Mnu
  107.     +Echo Option B selected from submenu 2
  108.  
  109. These are all useless menus, but you get the idea.  For a working example of a
  110. menu, see the VTKermit.Mnu file included in the distribution of VTKermit.
  111.  
  112. Technical facts and gotchas:
  113.  
  114.   1)  Empty text blocks (two item labels in a row) will cause problems, as
  115.     will almost all violations of these rules.  SET MENU-FILE JUNK.JNK
  116.     (where JUNK.JNK is not a valid menu file) will either die or be very
  117.     ugly.
  118.  
  119.   2)  There is a maximum of 20 menu items in a menu.  Beyond this limit, you
  120.     should use multiple menus.
  121.  
  122.   3)  The size of a text block (the set of lines beginning with plus-signs
  123.     following an item label) is limited to a total of 255 characters.
  124.     If you need to invoke a set of commands longer than this, you must use
  125.     a command file and invoke it with a TAKE command in the text block.
  126.  
  127.   4)  The text blocks are executed by creating an "instant-macro" similar to
  128.     one which you would create with the DEFINE command.  This means that
  129.     you may be unable to run menus from deeply nested TAKE files.  This is
  130.     probably not a problem in real life.
  131.  
  132.   5)  In the interest of higher performance, menus are not reread unless an
  133.     explicit SET MENU-FILE command is issued.  That is, a menu file will
  134.     be read the first time the menu is invoked, but if you leave the menu
  135.     (by selecting an item) and later return to the menu, you will reuse
  136.     the memory buffer holding the menu file from the last time.  This is
  137.     faster than rereading from disk, but it means that if you alter the
  138.     menu file you must give a SET MENU-FILE command to make it be read.
  139.  
  140.   6)  Dynamically allocated memory is used to hold the menu file, so if you
  141.     don't have enough memory you may be able to run VTKermit but not use
  142.     menus.
  143.  
  144.   7)  The maximum size of a menu file is something less than 7400 bytes.  This
  145.     is an assembly parameter and could be changed, at the expense of
  146.     memory piggishness.  Remember that text blocks are limited anyway, so
  147.     a larger buffer would not buy much.
  148.  
  149.   8)  The displayed menu is automatically sized and centered vertically and
  150.     horizontally on the screen -- you don't have to do anything, but you
  151.     can't change it either.
  152.  
  153.   9)  Since each item label is shown on a separate line, and is bounded by
  154.     spaces and vertical lines, the length of an item label must be 74
  155.     characters or shorter.
  156.  
  157.  10)  Unfortunately, due to the highly screen-oriented nature of the menu
  158.     display, the code has been written to run only on the IBM PC family
  159.     (including "100%" compatibles).  Someone who cared enough could
  160.     probably adapt it to another machine.
  161.  
  162. [End of MENU.DOC]
  163.